Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-11 / vs_804.zip / MAINTSRC.EXE / MAINT.DOC < prev next >

Wrap

Text File | 1991-12-03 | 24KB | 586 lines

Designing Your Clipper v5.01 Application by Vernon E. Six, Jr. December 3, 1991 CopyRight (c) 1991 by Vernon E. Six, Jr. All Rights Reserved World Wide Table Of Contents First Things First . . . . . . . . . . . . . . . . . . . . . 3 Database Dictionaries . . . . . . . . . . . . . . . . . . . . 3 Database Dictionary Maintenance Utility . . . . . . . . . . . 5 Create Database / Edit Header Information . . . . . . . . . . 5 Define Fields . . . . . . . . . . . . . . . . . . . . . . . . 6 Define Indexs . . . . . . . . . . . . . . . . . . . . . . . . 7 Delete Database . . . . . . . . . . . . . . . . . . . . . . . 8 Generate *.CH Files - Preprocessor . . . . . . . . . . . . . 9 Print Structure . . . . . . . . . . . . . . . . . . . . . . . 12 Renumber . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 First Things First The first step to designing your application is to determine exactly what output you want your application to be able to produce. This is where the interaction with your end user should be the highest. You should try to obtain as much information as possible relating to the desired reports, etc. After you have determined what the output requirements are, you should try to determine what data is necessary to obtain the desired output. As you are collecting this information, try to break the various pieces into logical groups. For example: logical groups for an accounts receivable system would be customers, invoices, payments, purchases, etc. This step is crucial for it is only through this process that you can develop your actual DBF file structures, index keys, etc. After you have broken the data into logical groups, try to define the relationships between the various groups. Example: An invoice has a relationship to the customer file because we surely would want to know to whom we sold something. The next step is to build a database dictionary. Database Dictionaries After you have decided what it is you want your application to do, you should design your database dictionary. In short, a database dictionary is nothing more than data about data. There are several advantages to using a database dictionary but the single largest advantage is the ability to allow your various functions to communicate with each other. i.e. UdfOne() might only need one index file for a particular database, but UdfTwo() needs several index files. By using a database dictionary, UdfOne() will open all the index files and maintain them so they are current for the next time UdfTwo() gets called and vice- versa. When using the Vern Six's Clipper ToolBox the database dictionary will contain the following information about each database... 1) default path to the actual DBF file, 2) whether or not the application is allowed to re-create a missing DBF file, 3) field definitions (data type, length, description, etc), 4) default field values, 5) field picture statements (for use with @ SAY .. GET statements, etc) 6) index file names, order and keys You should design your database dictionary in such a way that data within your application is not stored in multiple locations. For example, you probably would not want to store customer addresses with each invoice, but rather, you would store them in a customer file and point to them from within the invoice file with the use of an external key. The customer number in this case would be consider an external key. The entire datbase dictionary is contained in three database files (remember... it's merely data about data). These dictionary files are listed below with their associated file structures and index keys. ┌──────────────────────────────┐ ┌──────────────────────────────┐ │ _DictHdr.DBF File Structure │ │ _DictFld.Dbf File Structure │ │ # Field Name Type Len Dec │ │ # Field Name Type Len Dec │ ├──────────────────────────────┤ ├──────────────────────────────┤ │ 1 DBF_NAME C 8 0 │ │ 1 DBF_NAME C 8 0 │ │ 2 DESC C 40 0 │ │ 2 FIELD_NMBR C 3 0 │ │ 3 CREATE L 1 0 │ │ 3 FIELD_NAME C 10 0 │ │ 4 PATH C 60 0 │ │ 4 FIELD_TYPE C 1 0 │ ├──────────────────────────────┤ │ 5 FIELD_LEN N 3 0 │ │Index: │ │ 6 FIELD_DEC N 3 0 │ │ _DictHdr.Ntx: DBF_NAME │ │ 7 DESC C 40 0 │ └──────────────────────────────┘ │ 8 DEFAULT C 60 0 │ ┌──────────────────────────────┐ │ 9 PICTURE C 60 0 │ │ _DictNtx.DBF File Structure │ ├──────────────────────────────┤ │ # Field Name Type Len Dec │ │Index: │ ├──────────────────────────────┤ │ _DictFld: DBF_NAME+FIELD_NMBR│ │ 1 DBF_NAME C 8 0 │ │ _DictFl2: DBF_NAME+FIELD_NAME│ │ 2 ORDER C 2 0 │ └──────────────────────────────┘ │ 3 NTX_NAME C 8 0 │ │ 4 TYPE C 1 0 │ │ 5 KEY C 80 0 │ ├──────────────────────────────┤ │Index: │ │ _DictNtx: DBF_NAME+ORDER │ └──────────────────────────────┘ These dictionary database files must be available to your application at run time as several functions in Vern Six's Clipper ToolBox will be accessing them. These databases allow not only different functions within the same application to communicate amongst themselves, they also allow completely different applications to communicate. Example: If one application is an Accounts Receivable system and another application is a form letter generator, they could both access the same customer file via these database dictionary databases. NOTE: You can set an environment variable to point to a different directory if you do not want your database dictionary files in the current directory. Example: "SET DATADICT=C:\DATADICT\" Database Dictionary Maintenance Utility Vern Six's Clipper Toolbox comes with its own database dictionary maintenance utility called Maint.Exe. This utility will allow you to quickly and easily create and maintain your datbase dictionary. Of course, you could also create these dictionary databases with something like DBU.EXE or the like, but you really should be using MAint.Exe since it has some other features and will ensure data itegrity, etc. by not allowing you to forget something or create something incorrectly. The main screen within Maint.Exe is a pick list of all the databases in your application (figure 1). The following keys are active from this main screen... F1 - Help F4 - Copy F5 - Renumber F6 - Print Structure F7 - Generate *.CH Files F8 - Define Fields F9 - Define Indexs F10 - Edit Header Information Ins - Create Database Del - Delete Database Create Database / Edit Header Information Pressing either [Insert] or the [F10] key will take to the screen shown in figure 2. If you pressed the [Insert] key, you will be prompted for information about the new database you are creating. If you pressed [F10] you will be able to edit the information associated with the currently highlighted database. In either case, you will be prompted for the name, description, re-create setting, and default path for the specified database. The answers to these queries should be self explanatory with the exception of the default path. You would normally want to leave this field blank if you are going to be running your application in the same directory as your database files. Note: The user can override the default path setting by setting an environment variable such as "SET CUST=C:\DATA\ACCT\" After you have provided this basic information about the database file, you will be returned to the main screen of Maint.Exe. Define Fields You can create the actual database structure by pressing the [F8] key from the Maint.Exe main pick list. This will cause the structure pick list to be presented (figure 3). From here, you can press the [Insert] key to add a new field, the [Delete] key to delete a field, or the [F10] key to edit the currently selected field. When you either create or edit a field, you will be taken to the screen shown in figure 4. Each field is described in detail below... Nmbr is a programmer defined field that should contain the field number. I suggest that you number your fields in increments of five or ten so you can come back to this database and insert new fields in between existing fields. You should pad Nmbr with zeros on the left. Field Name is the actual name of the field and must conform to Clipper's field naming conventions. Field Name must be in all upper case. Type is the field type and must conform to Clipper's field type conventions. The valid choices are... C - Character, N - Numeric, L - Logical, D - Date, M - Memo. Type must also be in upper case. Length is a numeric value representing the entire field length (including any decimals points, etc.) Dec is a numeric value that represents the number of digits to the right of the decimal place. Dec is only valid for fields of Type N - Numeric. Description is a programmer defined description of what this field is for. You should try to be descriptive as this is the same field the users will see when they build an interactive query. Default Value is a programmer defined default value that VSG (Vern Six's Code Generator) will place in the field when it creates a "new" record. The value you place here must be of the same type as the field itself. i.e. strings have to be in quotes, etc. Picture Clause is a programmer defined picture clause that VSG will use when displaying/editing this field. The value you place here must be "stringified". i.e. a picture statement of 9999 must be written as "9999". NOTE: You can also reference the default value and picture statement in your own programs through the use of the database dictionary "include" files (see Pre-Processor below). Pressing [Escape] from the "database fields" pick list will return you to the Maint.Exe main screen/pick list. Define Indexs You can define the various index files that are required within your application(s) by pressing the [F9] key from the Maint.Exe main pick list. This will cause the index pick list to be presented (figure 5). From here, you can press the [Insert] key to add a new index, the [Delete] key to delete an index file, or the [F10] key to edit the currently selected index. When you either create or edit an index file, you will be taken to the screen shown in figure 6. Each field is described in detail below... Index FileName is a character field that should contain the actual name of the index file. Do not put the NTX extension on the end of this filename. Order is a character field that is used to determine the order in which the index files will be opened. This field should be a number padded on the left with a zero (if needed). Type is a character field that should contain the type of the index key. N - Numeric, C - Character, D - Date, L - Logical Key is the actual index key expression. You should place parenthesis around keys that are "simple" in nature (one field). While you are entering this field, you can press the [F5] key to select a field from a list. Delete Database Pressing the [Delete] key at the Maint.Exe main pick list will delete the currently highlighted database. You will be prompted to ensure this is really what you want to do. Once you delete the database, there is no way to recover it. Generate *.CH Files - Preprocessor Maint.Exe will generate "include" files for use in your programs and especially for use in VSG (Vern Six's Code Generator) generated programs. In general, you should generate the database dictionary include files after you have defined all the databases in your application and WHENEVER you change the database dictionary. To generate the include files, press [F7] from the main pick list in Maint.Exe. A sample include file might look like this... * Filename......: CUST.CH * * Author........: Vernon E. Six, Jr. * * Last Update...: 10/20/91 21:34:45 * * Notice........: Copyright (c) 1991 by Vernon E. Six, Jr. * All Rights Reserved World Wide * * Purpose.......: Data Dictionary DEFINEs for CUST.DBF #DEFINE _DEF_CUST_CODE SPACE(5) #DEFINE _DEF_CUST_NAME SPACE(35) #DEFINE _DEF_CUST_ADDR1 SPACE(35) #DEFINE _DEF_CUST_ADDR2 SPACE(35) #DEFINE _DEF_CUST_ZIP SPACE(5) #DEFINE _DEF_CUST_PHONE SPACE(14) #DEFINE _DEF_CUST_CONTACT SPACE(30) #DEFINE _DEF_CUST_COMMENTS SPACE(50) #DEFINE _DEF_CUST_LAST_PYMT DATE() #DEFINE _DEF_CUST_PYMT_AMT 0 #DEFINE _DEF_CUST_CURR_BAL 0 #DEFINE _DEF_CUST_PAST_DUE30 0 #DEFINE _DEF_CUST_PAST_DUE60 0 #DEFINE _DEF_CUST_PAST_DUE90 0 #DEFINE _DEF_CUST_BALANCE 0 #DEFINE _DEF_CUST_TTL_PYMTS 0 #DEFINE _DEF_CUST_TTL_CHGS 0 #DEFINE _DEF_CUST_ACCT_LOCK .F. #DEFINE _PIC_CUST_CODE "!!!!!" #DEFINE _PIC_CUST_NAME REPLICATE("X",35) #DEFINE _PIC_CUST_ADDR1 REPLICATE("X",35) #DEFINE _PIC_CUST_ADDR2 REPLICATE("X",35) #DEFINE _PIC_CUST_ZIP REPLICATE("X",5) #DEFINE _PIC_CUST_PHONE "(999) 999-9999" #DEFINE _PIC_CUST_CONTACT REPLICATE("X",30) #DEFINE _PIC_CUST_COMMENTS REPLICATE("X",50) #DEFINE _PIC_CUST_LAST_PYMT "99/99/99" #DEFINE _PIC_CUST_PYMT_AMT "9999.99" #DEFINE _PIC_CUST_CURR_BAL "9999999.99" #DEFINE _PIC_CUST_PAST_DUE30 "9999999.99" #DEFINE _PIC_CUST_PAST_DUE60 "9999999.99" #DEFINE _PIC_CUST_PAST_DUE90 "9999999.99" #DEFINE _PIC_CUST_BALANCE "9999999.99" #DEFINE _PIC_CUST_TTL_PYMTS "9999999.99" #DEFINE _PIC_CUST_TTL_CHGS "9999999.99" #DEFINE _PIC_CUST_ACCT_LOCK "Y" The following is a sample program that uses this include file... * Filename......: AddCust.Prg * * Author........: Vernon E. Six, Jr. * * Last Update...: Thu 10-24-1991 19:27:49 * * Notice........: Copyright (c) 1991 by Vernon E. Six, Jr. * All Rights Reserved World Wide * * * Dialect.......: Clipper v5.01 #include "INKEY.CH" #include "CUST.CH" FUNCTION AddCust() ***** * Simple routine to demonstrate use of data dictionary and related functions * for dCUG() "Saturday Gang" ***** LOCAL getlist := {} LOCAL c_CustCode := _DEF_CUST_CODE LOCAL l_AcctLock := _DEF_CUST_ACCT_LOCK LOCAL c_Name := _DEF_CUST_NAME LOCAL c_Addr1 := _DEF_CUST_ADDR1 LOCAL c_Addr2 := _DEF_CUST_ADDR2 LOCAL c_Zip := _DEF_CUST_ZIP LOCAL c_Phone := _DEF_CUST_PHONE LOCAL c_Contact := _DEF_CUST_CONTACT LOCAL c_Comments := _DEF_CUST_COMMENTS // // Open the customer database // IF .NOT. VS_OpenDbf( "CUST" ) VS_Die( PADC("Which Way Did It Go?",40),PADC("Which Way Did It Go?",40) ) ENDIF VS_NewScrn() @ 05,05 SAY "Customer Code: " GET c_CustCode PICTURE _PIC_CUST_CODE @ 06,05 SAY "Account Locked? " GET l_AcctLock PICTURE _PIC_CUST_ACCT_LOCK @ 10,05 SAY "Street Address: " GET c_Addr1 PICTURE _PIC_CUST_ADDR1 @ 11,05 SAY "Box, suite, etc: " GET c_Addr2 PICTURE _PIC_CUST_ADDR2 @ 12,05 SAY "Zip Code: " GET c_Zip PICTURE _PIC_CUST_ZIP @ 15,05 SAY "Telephone: " GET c_Phone PICTURE _PIC_CUST_PHONE @ 16,05 SAY "Contact: " GET c_Contact PICTURE _PIC_CUST_CONTACT @ 20,05 SAY "Cmts: " GET c_Comments PICTURE _PIC_CUST_COMMENTS READ BEGIN SEQUENCE IF LASTKEY() = K_ESC BREAK ENDIF IF .NOT. CUST->( VS_AddRec() ) BREAK ENDIF REPLACE CUST->CODE WITH c_CustCode REPLACE CUST->ACCT_LOCK WITH l_AcctLock REPLACE CUST->NAME WITH c_Name REPLACE CUST->ADDR1 WITH c_Addr1 REPLACE CUST->ADDR2 WITH c_Addr2 REPLACE CUST->ZIP WITH c_Zip REPLACE CUST->PHONE WITH c_Phone REPLACE CUST->CONTACT WITH c_Contact REPLACE CUST->COMMENTS WITH c_Comments CUST->( dbUnlock() ) END SEQUENCE dbCloseAll() RETURN(NIL) *** EOF: AddCust() ********************************************************** Print Structure Pressing the [F6] key at the main pick list in Maint.Exe will cause the file structure and index keys for the currently selected database to be printed to the printer on LPT1:. You will be prompted for the printer name, etc. Renumber Pressing the [F5] key at the main pick list in Maint.Exe will cause Maint.Exe to assign new sequence numbers to the fields in the currently selected database. This is most commonly used when you have added several new fields to a database and have exhausted the number of fields you can insert between two fields. i.e. If you need to insert a field between field number "005" and field number "006", you could not do it. Renumber will spread these tightly grouped fields apart again. In this example, 5 would remain as 5 and 6 would become 10, 7 would become 15, 8 would be come 20, etc. Copy Pressing [F4] will allow you to copy the currently selected database structure and index keys to a new database structure, etc. This is useful for when you create a database and later need a similar database that only requires a few modifications to the structure. WARNING!! If you copy a database, you have also copied the index file names, keys, etc. Be sure to edit the index files for the new database, or you will have two databases sharing an index file. This is most certainly a one way ticket to ErrorSys() at runtime.